/*
 *  Copyright 2010 Andrew Kroh
 *
 *  Kroh-IO is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  Kroh-IO is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package kroh.io;

import java.util.EventListener;

/**
 * <p>
 * Propagates various communications port ownership events. When a port is
 * opened, a <code>CommPortOwnership</code> event of type
 * <code>PORT_OWNED</code> will be propagated. When a port is closed, a
 * <code>CommPortOwnership</code> event of type <code>PORT_UNOWNED</code> will
 * be propagated.
 * </p>
 * 
 * <p>
 * Multiple applications that are seeking ownership of a communications port can
 * resolve their differences as follows:
 * </p>
 * 
 * <ul>
 * <li>ABCapp calls <code>open</code> and takes ownership of port.</li>
 * <li>XYZapp calls <code>open</code> sometime later.</li>
 * <li>While processing XYZapp's <code>open</code>, <code>CommPortIdentifier</code>
 * will propagate a <code>CommPortOwnership</code> event with the event type <code>
 * PORT_OWNERSHIP_REQUESTED</code>.</li>
 * <li>If ABCapp is registered to listen to these events and if it is willing to
 * give up ownership, it calls <code>close</code> from within the event
 * callback.</li>
 * <li>After the event has been fired, <code>CommPortIdentifier</code> checks to see
 * if ownership was given up, and if so, turns over ownership of the port to
 * XYZapp by returning success from <code>open</code>.</li>
 * </ul>
 * 
 * Note: When a <code>close</code> is called from within a
 * <code>CommPortOwnership</code> event callback, a new
 * <code>CommPortOwnership</code> event will <i>not</i> be generated.
 */
public interface CommPortOwnershipListener extends EventListener
{
    /**
     * The port just went from unowned to owned state, when an application
     * successfully called CommPortIdentifier.open.
     */
    public static final int PORT_OWNED = 1;

    /**
     * The port just went from owned to unowned state, when the port's owner
     * called CommPort.close.
     */
    public static final int PORT_UNOWNED = 2;

    /**
     * Ownership contention. The port is owned by one application and another
     * application wants ownership. If the owner of this port is listening to
     * this event, it can call CommPort.close during the processing of this
     * event and thereby give up ownership of the port.
     */
    public static final int PORT_OWNERSHIP_REQUESTED = 3;

    /**
     * Propagates a CommPortOwnership event. This method will be called with the
     * type set to one of the variables PORT_OWNED, PORT_UNOWNED, or
     * PORT_OWNERSHIP_REQUESTED.
     * 
     * @param type
     *            type of ownership change
     */
    public abstract void ownershipChange(int type);
}
